Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/telecomm/flashdoc.lzh/SECRETS.TXT

Text File | 1992-02-21 | 119KB | 4,527 lines

.____________________________________________________.
|                                                    |
|  S  E  C  R  E  T  S      O  F      F  L  A  S  H  |
|                                                    |
\====================================================/


 How to make the most of Flash's DO language:
 Things they never seem to tell you at the store.




 _________________________

 B Y   A L   F A S O L D T

 -------------------------



Technology Writer, Syracuse Newspapers and Newhouse News Service

Computer pagination trainer and programmer, the Herald-Journal,
the Herald American and the Post-Standard

Syracuse, New York



Copyright (C) 1992 by Al Fasoldt. All rights reserved.






P A R T   1 :   I N T R O D U C T I O N
---------------------------------------



This article is for newcomers and experienced Flash users
alike. Many parts of this guide contain information that may not
be generally known to most users.

Flash was distributed by Antic Software, a company that is no
longer doing business. However, Flash is still available from ST
and TT software outlets.

Many of these tips may also be applicable for users of Flash II,
a new telecommunications program from Missionware. Flash II was
scheduled to be released by mid-1992.






P A R T   2 :   W H A T   T H I S   I S   A L L   A B O U T
-----------------------------------------------------------



Flash, a telecommunications program for the Atari ST, was
distributed by Antic Publishing's software division from the
mid-1980s until the company ceased operation recently. Flash is
now an orphan in the marketplace, although the copyright law in
the United States and elsewhere still protects the software from
infringement. Without direct manufacturer support, however, the
only way Flash users can receive help is through the individual
efforts of experienced Flash programmers who are willing to take
the time to offer advice and assistance. One avenue for such
help is the nationwide network of telecommunications services.
These services, which include GEnie, Compuserve, BIX, Delphi and
America Online, have active ST users who have used Flash for
five or six years. Many of them have written extensive Flash
scripts that take advantage of Flash's powerful programming
language.

As one of those Flash programmers, I am offering this expanded
documentation as a means of keeping the thousands of current
Flash users up-to-date on how to use Flash's DO language -- its
scripting commands -- in ways that may not be obvious in Flash's
original, sparse documentation. This document is free, and I
encourage you to share it in electronic or printed form with
anyone else. But in doing so you must observe these three
common-sense requirements:

1. This document cannot be distributed in any altered form.
This means you must not make excerpts of it, and you must not
remove the author's name and copyright notice.

2. This document must not be distributed with any other
document or software program, other than the author's Flash DO
files and any other support files that are archived with this
text file. This means you must not include Flash itself with
this documentation if you share it with anyone else.

3. The author cannot be responsible for the use or misuse of
any of the files included with this documentation. This means
you are on your own when you try out the DO files and the
support program(s), and cannot blame me if any of them cause a
problem.

If you have suggestions or comments, or would like your own DO
files or support programs included in revisions of this archive,
you can reach me at any of these addresses:

Email:

GEnie - "a.fasoldt"; BIX - "afasoldt"; AOL - "Al Fasoldt"

U.S. mail - Syracuse Newspapers, Box 4915, Syracuse, NY 13221



** A note about Flash versions **

The last release of Flash was Version 1.61. However, this
version is usually referred to as Version 1.6. According to the
authors of Flash, Version 1.6 was never actually released, and
all versions that carry a "1.6" designation are actually 1.61.
This documentation is intended for users of 1.6/1.61 only, since
the script language was made more powerful in that release. If
you own an earlier version of Flash, an upgrade to 1.6/1.61 is
highly recommended. A patch file distributed free on many
telecomm services will automatically upgrade previous versions
to the last version.






P A R T   3 :   W H A T   A R E   S C R I P T S   A N Y W A Y ?
---------------------------------------------------------------


** Scripts tell the computer what to do **

Many telecommunications programs have built-in scripting
abilities. In other words, they are able to follow a written
list of instructions much like the scripts that actors must
follow. A telecomm script, like the ones used in plays and
movies, contains lines that must be said (or sent to another
computer, in the case of the telecomm script), and it may
contain such things as cues, also. (The computer may be told to
wait until a certain time has passed before it does something
else, for example.)

But telecomm scripts usually have many more features than this.
The scripting facility built into Flash, called the "DO"
language, can instruct the computer to perform any of these
functions:

 - Suspend action until a specific time

 - Wait to get an exact word or phrase from the other computer
before proceeding

 - Show a dialog box on the screen and ask for user input

 - Ring the computer's bell (and even ring the bell on the other
computer)

 - Dial a number and redial it up to 99 times if it's busy

 - Delete a file on a disk drive

 - Check to see if a particular file exists

 - Check the contents of any file, line-by-line

 - Run a program

 - Program and execute a function key remotely

 - Check to see if an upload or download was successful and try
it again, if desired

 - Look back to see what the last information the other
computer sent actually said


And much more -- so much more, in fact, that many casual Flash
users are unaware of the full power of the DO language. For
example, a DO script can assemble a text file from information
that is sent across from another computer and save that text
with the date as part of the name. For another example, a DO
script can even modify itself by creating a new DO file and then
running it.

You'll see how to do all of this and more in this
documentation. But first, we'll need to understand the basic way
a DO script is put together.




** A note on the way commands and keystrokes are shown **

Keyboard keys are listed in the text with angle brackets before
and after them, like this:

 <tab>.


Key combinations are shown the same way, with a hyphen between
them, like this:

 <control-C>.


Many commands are not complete without parameters. In simple
terms, parameters make a command more specific. The place where
parameters go is shown like this:

 [...]


Quotation marks are sometimes used to set off parts of the
text, like this:

 A ".DO" file extender.


Do NOT type the quotes when you follow the example.

However, quotation marks are also used within DO scripts for
various purposes. Whenever an example of quotes within a DO
script is given, you will see a reminder that the quotation
marks MUST be included in the script.

Finally, grammarians who are reading this carefully may notice
that this text breaks the rules of punctuations freely.
Whenever this is done, it's for clarity. (If you're wondering
what I am referring to, here's an example. In DO script writing,
we use ">". The period probably should have gone inside the
quotation marks -- like this: ">." -- but that would make the
example a lot harder to follow.)




A note on the way pathnames are shown
-------------------------------------


By convention, filenames that are listed in the parameters
sections of this document have the name "filename.ext"; drives
are listed as "d:" -- with the colon included as part of the
required drive specifier. The "d:" does not stand for any
particular drive; it can be "a:" through "p:" on some STs and
TTs and "a:" through "z:" on others.

The ST and TT operating system uses a common method of
indicating which command parameters are pathways (drives and
folders) and which are files. Pathways can be relative or
absolute, depending on how they are written. An absolute pathway
always has a backslash at the end, whether a filename follows it
or not. A relative pathway does not have a slash after it. And
files, in turn, never have slashes after their names.

Here are some simple examples:

An absolute pathname:

 c:\flash\dofiles\

This indicates that Flash should perform some operation in the
folder named "dofiles" inside another folder named "flash" in
the root directory of the c: drive.

A relative pathname:

 c:

This indicates that Flash should perform some operation in
whatever pathway it was already using on the c: drive. It may
seem obvious to some that the "c:" could be left out, but this
is not necessarily the case. For example, if Flash's default
pathway had been "c:\flash\" and was then changed to
"a:\messages\", any time Flash returns to "c:" (without a
backslash) it will arrive at the location it was in the last
time it accessed the "c:" drive.

A pathname and filename:

 c:\flash\dofiles\callbbs.do

NOTE: You must be sure to include the backslash between
"dofiles" and "callbbs.do" so that the operating system does not
look for a file named "dofiles" in the "c:\flash\" directory.






P A R T   3 :   H O W   S C R I P T S   A R E   W R I T T E N
-------------------------------------------------------------




Here are guidelines for writing and executing scripts. All of
them are explained in detail later.


In Flash DO scripts, commands should be:

1. Written in plain text, also called ASCII.

2. Written on a separate line -- until the script has been
tested and is known to work properly. You then have the option
of combining many commands on one line.

3. Preceded by a ">" character.

4. Followed by a "|" character.

5. Written with comments at the beginning giving the name of the
script and at any point in the script where complicated commands
are operating.

6. Written in lower case.



Flash DO scripts can be:

1. Any practical length (although short scripts execute faster
than long ones).

2. Named anything you want, with any choice of filename
extender -- although you should standardize the extenders to
make scripts easy to organize.

3. Executed from any folder or from a root directory on a
floppy disk, hard disk or ramdisk.



Flash scripts can be executed in five ways:

1. From Flash's command line, which is accessed from the
terminal screen by pressing the <insert> key.

2. From an alt-key combination.

3. From a function key.

4 From another script.

5. From Flash itself, automatically, whenever Flash runs.




** The write of passage **


Flash scripts must be written in plain text.
-------------------------------------------

Word processors usually store their text files in a form that
includes codes for such things as boldface, font sizes, line
centering and other display attributes. While this is perfectly
fine for documents that are printed out, it causes a great deal
of trouble for texts that are used as script files. These texts
must not have any word-processing codes at all; if they do, the
program running the script will either stop running the script
or, in one of the favorite phrases of programmers, will "do
something unpredictable."

The easiest way to make sure this doesn't happen is to write
Flash scripts by using Flash's own text editor. The Flash text
editor is powerful enough to serve as a primary text editor for
all script writing, although it does lack many of the niceties
of the current standard text editor for the ST, STeno, from
Gribnif Software. (The screen fonts can be made large or small
in STeno, for example, and -- best of all -- STeno can be run as
a GEM desk accessory while you are running Flash.)

But Flash's own text editor is ideal if you do not own STeno.
Flash's editor offers search-and-replace functions, block-delete
and block-save operations, text-file insert, easy scrolling by
the cursor keys or GEM window bars, and two big advantages --
immediate access to Flash's GEM-bar menus, including the Help
menu, and the ability to test a script as you are writing it.

No matter which text editor you use, you must turn off word
wrap before you write or load a script file. You do not want the
text editor to decide where lines end; it probably will wrap
some lines around and ruin the script. Flash's editor can load
texts with inordinate line lengths (STWriter files, for example,
can have line lengths of hundreds or even thousands of
characters), but Flash itself runs into difficulties if scripts
include lines that are longer than 102 characters. This means
that you can write scripts with line lengths of, for example, 90
columns (a "column" in text processor terminology contains one
character), but unless you are careful you may have a problem
making sense of your scripts if they are written that way; since
Flash's editor will not show any characters past the 76th column
without horizontal scrolling, you may forget that some lines
extend past the right edge of the screen when you are checking
your scripts. Play it safe and keep your line lengths down to 65
to 75 columns.

Both STeno and Flash's own editor save texts in ASCII. The word
stands for the American Standard Code for Information
Interchange, and represents a set of standards that nearly all
personal-computer manufacturers follow for the internal codes
that are used for all regular keyboard characters. In other
words, the letter "A" has the same ASCII code -- "10" in decimal
notation -- on the ST, an IBM PC, or even an AT&T
teletypewriter. (The ASCII standard also defines the common
codes for such "characters" as <control-C> and <control-L>,
which normally cannot be seen on a computer screen because they
usually signal the computer to do certain things. However, both
STeno and Flash's own editor allow you to enter control
characters directly into a script.)

However, if for some reason you would rather write Flash
scripts on a word processor, such as WordPerfect, WordUp, That's
Write, WordFlair, WordWriter, 1st Word or STWriter, you will
have to make sure you save the scripts to disk as ASCII files.
Some word processors have an ASCII Save option and others can
only save files as ASCII when they are "printed" to a disk file.
If you choose this method, be sure to set the left margin at "0"
and the right margin at about 75, and, if necessary, set top and
bottom margins to "0" also. Then, after you have saved the
scripts as ASCII files, run Flash and load them, one by one,
into Flash's text editor and look them over carefully. (Turn
off Flash's word wrap whenever you do this.) Then save them
again from within Flash.

(A big drawback to using a word processor for writing scripts
is that the word processor is not likely to let you insert
control characters in the text that it saves as ASCII. The
typical exception is <control-I>, which has no use in most
script files anyway. And if this isn't enough of a reason to
avoid a word processor when writing scripts, there's the added
trouble of reconverting ASCII-based scripts back to your
favorite word processor's format whenever you want to edit them.
My advice: Use STeno or Flash's own editor.)



Scripts should be written with each command on a separate line.
---------------------------------------------------------------


Scripts are written in a kind of code that looks like English
words or abbreviations. Until you become an expert at script
writing and script editing, you should always write each command
on a line of its own. This makes the task of debugging a script
much easier, since you'll have a lot better chance of
understanding what each command is trying to do when they're
separated.

Flash does not require each command to be on a separate line,
however. It will run scripts without a problem if commands are
bunched up. In fact, scripts will run slightly faster that way.
(Technically, the reason is that Flash parses or interprets
scripts one line at a time when they are run, and it will parse
a few long lines faster than a lot of short ones.) But until you
are entirely comfortable with the way each command works, you're
better off keeping them on separate lines.



Commands must be preceded by a ">" character.
---------------------------------------------


Commands must have a right-facing angle bracket in front of
them. (You don't have to put the angle bracket right next to the
command; you can put spaces between them if you want. For more
on this technique, see Appendix XX, "Making scripts more
readable.")

The angle bracket, also called the "greater-than" symbol, is
the only way Flash can tell that the word that follows the
bracket is an actual command.  The ">" character should be
considered as part of every Flash command, even if commands are
bunched up on a single line. Every time Flash sees an angle
bracket, it expects that the next characters it sees will be a
command. (Flash will ignore that bracket and any of the other
special characters used in scripts if they are enclosed in
quotes, however.)



Commands must end with a "|" character.
---------------------------------------


Once Flash encounters a ">" character in a script, it accepts
all the characters EXCEPT SPACES following the ">" as parts of a
command until it comes to a vertical bar symbol. The "|" symbol
is shown on the ST keyboard, in typical IBM fashion, as two
short vertical bars, one on top of the other. (You get it by
typing <shift-\>.)

The vertical bar symbol has a double job in Flash. It also
stands for a carriage-return/line-feed combination -- a
<return>, in other words. We'll see how Flash uses "|" for just
a <cr/lf> later.



Commands should be commented.
-----------------------------


A comment in a programming language is any part of the script
that is ignored when the script is run. In Flash, a comment is
indicated by two asterisks placed right after a ">" symbol. At
the end of each comment, Flash requires a "|" symbol. A typical
comment might look like this:

 >** This is the start of the CALLBBS routine.|


Comments can be any reasonable length. Even though it seems
obvious that comments should be self-contained on one line, this
is not the case at all. Flash considers any length of text a
comment if it starts with a ">" and ends with a "|". This means
that entire paragraphs or groups of paragraphs can be comments.
(In testing, I used a text more than 180K long as a comment,
without a problem ...  except, of course, for the dreadful
slowdown in the execution of the script.)

This unusual property allows programmers to treat comments as
blocks of text, readily set off from the main sections of the
script. Comments could look like this:


>**

This part of the script calls the Zork BBS and waits for 2
minutes for an acceptable connection. If it does not find one, it
calls back 15 minutes later.

|



Note that both the start-comment and end-comment command
characters -- ">**" and "|" -- were on lines of their own. This
may seem unorthodox, but works fine. It is especially easy to
read the comment, since it does not have any asterisks or
vertical-bar symbols as part of the comment text.

Experienced programmers always place comments in their work;
they have no choice, because the alternative would be to trust
everything to memory. Commented commands and subroutines are
also a sign that the programmer knew what he or she was doing.
Many veteran Flash users have seen scripts that performed
complicated tasks in needlessly serpentine ways, largely because
the script writer had gotten lost deep within the script and had
to wiggle within the commands to get back out. Scripts that are
commented can help avoid this, and as a result the scripts will
be more powerful and usually will run faster.

Remember that comments slow down the execution speed of DO
scripts. Even though Flash does not treat anything within a
comment as a command, Flash looks through all comments for
improper command syntax. (This is bizarre, to say the least, but
it cannot be avoided.) Flash will not allow unpaired quotation
marks in comments, for example. This means you will not be able
to use contractions in comments unless you spell them with
double apostrophes -- like this:  "Don''t use single
apostrophes; Flash can''t execute the DO script otherwise." If
this looks as silly to you as it does to me, just avoid
unnecessary contractions, apostrophes and quotation marks
altogether in DO files.



Commands should be written in lower case.
-----------------------------------------


Some scripting languages require upper-case commands, and some
require lower-case commands. Flash can accept them either way,
so you'll probably find that lower-case entries are better
because they are easier to read. Two exceptions are any
single-letter variable names, which in Flash are indicated by a
dollar-sign symbol followed by a letter from A to Z and which
can be confusing in lower case, and the Flash command for a
label, "L", which can be misidentified as the number "1" if it
is written in lower case.




** The play's the thing **


Scripts can be any practical length.
------------------------------------


You will not find a limit to DO file lengths in any normal use.
My tests have shown that scripts longer than 100K caused no
problem other than a severe slowdown in execution. If you write
a very long script that seems to take a few minutes to load and
run, try breaking the script into a couple of parts and running
those parts from a master script.



Scripts can have any name you want.
-----------------------------------


Alan Page, co-creator of Flash, began the convention of naming
scripts with a ".DO" extender. (A filename extender follows the
period at the end of the filename and can be one to three
characters long.) But there's nothing that prevents you from
using any other extender or, of course, no extender at all.
Flash will run any DO file regardless of its name. But you'll
find it a lot easier to keep track of your scripts if they all
have the same filename extender, whether it is ".DO" or ".SCR"
or something else. I suggest the conservative course of sticking
to "filename.do" to avoid confusion, since no other programs for
the ST currently use the ".DO" extender.



Scripts can be stored and run from any folder or path.
------------------------------------------------------


In its default state, without any prior modification of its
file paths, Flash expects to find scripts in the same folder or
path that it was run from. However, you can specify any other
location when you run a DO script, or you can change the default
directory through a "cd" (change directory) command within a
script. You can also issue the "cd" command from Flash's command
line, a function key or the GEM menu bar in Flash. You can even
use a special script to search all possible paths for DO files
automatically, letting it set the default once it has found the
files.




** Running in place **


Run a script from the command line.
--------------------------------------


The usual way of running a DO file is to use Flash's command
line. The command line appears at the bottom of the terminal
screen (not the GEM window screen) any time you press the
<insert> key. When the command line appears, type "do" and a
space and then the full name of the script -- with the pathname
preceding it, if necessary --  and then press <return>.



Run a script by pressing <alt-A>.
---------------------------------


From Flash's terminal screen, you can press <alt-A> to open a
file selector from which to choose a DO script. Double-click on
the script you want and it will execute.



Run a script from a function key.
---------------------------------


Using Flash's function-key editor, you can program a function
key to run a script. Type the same command into the function key
template that you would type at the command line. Make sure the
function key command ends with a "|" symbol, which is Flash's
equivalent of a <return> key, or the script will not execute.
(Flash waits for you to press <return> in that case.)

Note that function keys are quite powerful. They can be
programmed from within a script, and can even be used within
scripts as "gosubs."



Run a script from another script.
---------------------------------


This is so obvious that it may be missed by some users: Flash's
scripts can be chained or nested. This offers a particular
advantage to a programmer, since scripts can be broken up into
easy-to-write sections and run separately. Ideally, a master
script should be written to run sub-scripts, as will be
explained in some detail later.

The Flash command to run a DO script within another script
looks like this:

 >do pathname\filename.do|



Run a script automatically when Flash boots
-------------------------------------------


Flash's "auto" function, which is perhaps the least known of
the program's main features, will instruct Flash to execute a
single command when it is first run. This seems fairly limiting,
but it is not -- if you make that single command the "DO"
command, which runs a script. Since a DO script can contain any
number of commands, there is no real limit on what Flash can do,
automatically, when it boots up.

Setting up the "auto" function involves nothing more than
pressing the <insert> key from Flash's terminal screen, typing
"auto," a space, the command you want executed on bootup, then
<return>. You must then save Flash's configuration file to the
filename "FLASH.CNF" -- the configuration file it always looks
for and loads when it runs.






P A R T   4 :  B A S I C   F L A S H   C O M M A N D S
------------------------------------------------------




The abbreviated command name is listed as the primary one, with
the longer name, if any, listed in parentheses. While Flash
often has two ways of giving a particular command -- "baud" and
"ba," for example -- by convention, the short name is preferred.
With the exception of "load," "log" and "ifin," Flash itself
does not scan past the first two letters of a command name
anyway.

Parameters, if any, should be placed after the command name.
Commands that take parameters are listed this way:

 >ba [...]

If parameters are optional, commands are listed this way:

 >mf [...optional]

Please note that in each case in which a variable can be
substituted for a parameter, more than one variable can be used
if they are concatenated (combined without spaces between them).
For example, if the variable $X contains the characters
"filename" and the variable $Y contains the characters ".ext",
you can give Flash the command "lo ca $X$Y" and it will
understand it as "lo ca filename.ext".



The building blocks
-------------------


Many script commands help build the structure of a DO file.
They include labels, jumps and conditionals. Within the
structure, variables can help keep the script from becoming
top-heavy. These commands are presented first to point out ways
to build your scripts as economically as possible.



- LABELS

Command:

 >L: [...] (label)

Action:

Marks a line in the script that can be quickly accessed through
a "jmp" command. Flash skips everything between its previous
point in the script and the label, and begins its next execution
at the line following the label. The label should be by itself
but does not have to be. Labels can be as long as the width of
the screen, but short labels are best. Labels must not include a
space.

Parameter:

 labelname or label_name

(Can be written in upper or lower case or any mixture of the
two, but Flash does differentiate between capital letters and
lower-case letters when it looks for labels. This means
"labelname" is not the same as "LabelName")

Examples:

 >L: BeginCall|

 >L: a_really_long_label_but_it_is_OK_if_it_has_no_spaces|



- JUMPS or GOTOS

Command:

 >jmp [...]

(also abbreviated "jm")

Action:

Forces the script to look for the label given as the
parameter and then to execute the command following the label. It
is a misconception that labels must be on lines by themselves;
they do not need to be. (See one of the examples below.)

The parameter must be spelled exactly the same as the label,
including upper- and lower-case letters.

Note: The "jmp" command works as a standard "goto" in scripting
languages, not as a "gosub." That is, command execution will
not return to the line following the "jmp" command. However,
Flash has an undocumented "gosub" feature, explained in "How to
use 'gosubs' in scripts" below.

Parameters:

 labelname

or

 label_name

Examples:

 >jmp BeginCall|

 >jmp a_really_long_label_but_it_is_OK_if_it_has_no_spaces|

Context examples:

>L: begin|
>ifi $X "Yes" jmp end|
>ifi $X "No jmp begin|

...

>L: start|>wt 08:45:00|>do callbbs.do|>jmp start|



- VARIABLES

Command:

 $X [...]

Action:

Places a character string (any letters or characters) into a
storage area represented by "$A" through "$Z". This is the most
simple of many ways variables can be set. The parameter does not
have to be in quotation marks, although the special symbols ">"
and "|" must be set off with single quotes if they are assigned
to a variable. There is one other variable in Flash. It's "$!",
which represents the contents of Flash's single-line input
buffer (the area where incoming data is stored while it is being
received from the modem). You can't assign your own character
string to "$!", but otherwise it works like the other variables.

Parameters:

 [any letters or numbers; the limit is just over 100]

 $Y (any other variable)

Examples:

 >$X c:\download\clock.prg|

 >$X $Y|

 >$Z '>Hello|'|


Context examples:


** Using a variable with an Xmodem upload command **

>$X a:\temp\browneye.spc|
>ul xm $X|
>**
Sets X to a filepath and filename,
then uploads that file.
|


** Setting one variable from another and combining variables **

>$X c:\letters\|
>$Y $X|
>$Z tomother.txt|
>ul xm $Y$Z|
>**
Sets X to a pathname and then sets Y to X.
Sets Z to a filename, then combines Y and Z for the Xmodem
upload parameter.
|


Regular variables and the buffer variable are covered in greater
detail below.



- COMMENTS or REMARKS

Command:

 >** [...]

Action:

Treats text following the "**" as a comment or a remark until
the next "|" is reached. Comments can be as lengthy as you want,
but long comments slow down the script. Although Flash is
supposed to ignore the text in a comment, it checks comment
lines for command syntax and will show an error if it encounters
a non-paired quotation mark (either a single-quote or a
double-quote mark) within the comment. If you use contractions
within comments, they must have double apostrophes.

Comments can be dressed up with tabs and internal spaces, and
they can be set off in their own text blocks.

Parameters:

 [any text]

Example:

>**

This is a comment. The text can start on its own line.

Blank lines are OK. The vertical bar symbol ("|") can be placed
on its own line after the comments.

Note that if the bar is surrounded by quotes, Flash will not
count it as an end-command character.

|



- SCRIPT EXECUTION

Command:

 >do [...]

(execute a script)

Action:

Run a script within another script. The nesting limit is three.
Be careful when running scripts from a master script, since you
may exceed the nesting limit without realizing it.

The "do" command is one way that Flash provides the equivalent
of a "gosub" -- a command that branches to another set of
instructions and then returns when the other instruction is
finished. (The return takes effect at the next command from the
one that called the sub-script.) You must give the full filename
of the script; Flash will not run scripts with ".DO" extenders
unless ".DO" is specified in the "filename.ext" parameter.

Parameters:

 c:\filepath\dofile.ext

 $X (any variable containing a filespec)

Example:

 >do callbbs.do|
 >do c:\flash\dofiles\settime.do|
 >do c:\flash\do\$P|

Context example:

** Scripts that are run from a master script based on the day **


>L: top|
>do c:\flash\do\setday.do|
>ifi $D "Monday" do callbix.do|
>ifi $D "Monday" jmp cleanup|
>ifi $D "Tuesday" do callbbs.do|
>ifi $D "Tuesday" jmp cleanup|
>ifi $D "Wednesday" do getmail.do|
>ifi $D "Wednesday" jmp cleanup|
...
>L: cleanup:
>do arcmsgs.do|
>wt 00:01:00|
>jmp top|





The setup
---------


Some of the script commands deal only with communications port
parameters. They are usually set only once for each session in
which Flash is run.



- BAUD RATE

Command:

 >ba [...]|

(baud)

Action:

Sets the baud rate, known more accurately as the
bits-per-second rate. Your modem must support the rate you
choose. If you are setting up a direct connection through a
null-modem cable, you may find text transfers falter at 9600 and
19,200 bps.

Parameters:

 11 [110 bps]

 30 [300 bps]

 60 [600 bps]

 12 [1200 bps]

 24 [2400 bps]

 48 [4800 bps]

 96 [9600 bps]

 19 [19200 bps]

 $X [any variable containing a bps number]


Examples:

 >ba 2400|

 >ba $X|




- DIALING

Command:

 >di [...]

(dial)

Action:

Tells Flash to dial a number. If the "#" parameter is given,
Flash dials the number following the pound sign. If a name is
listed as a parameter, Flash looks in the dialing directory for
the first name that matches the letters given in the parameter
and then dials the number listed for that entry.

Parameters:

 # (followed by a telephone number)

 "name" (a listing in the dialing directory; it can be
abbreviated)

Examples:

 >di #123 456-7890|

 >di harry|



- DUPLEX

Command:

 >du [...]

(duplex)

Action:

Sets the echo to remote or local (full or half). This is
loosely called full or half duplex, although the term is not
accurate. In remote echo (full duplex), what you see on your
screen comes from the other computer, even if it is what you are
typing. (The signal goes out to the other computer and is echoed
back to yours for display on your screen.) In local echo (half
duplex), the words you type are displayed by your own computer.

Parameters:

 fu (full)

 ha (half)

/  (a toggle, from full to half or vice versa)

 $X (any variable containing "full," "half" or "/")

Examples:

>du full|

>du /|

>du $X|




- ECHO

Command:

 >ec [...]

(echo)

Action:

Sets the echoplex, in which Flash can send back all characters
received from the remote computer, regardless of the "duplex"
setting. With echo set to "off," flash does not send any
characters back.

Parameters:

 on

 of (off)

/  (a toggle, from on to off and vice versa)

$X (any variable containing "on," "off" or "/")

Examples:

 >ec on|

 >ec /|

>ec $X|



- HANGUP

Command:

 >hg

(hang up)

Action:

Hangs up on the other modem or on the dead line.

Parameters:

 none

Example:

 >hg|



- LINE FEEDS

Command:

 >lf [...]

("line feeds"; the command must be given in its abbreviated
form only)

Action:

Changes the way Flash handles the ends of text lines that are
received or transmitted in text transfers. With line feeds on,
every <return> is converted to a <return>/line-feed combination.
With line feeds off, nothing is converted. Set this to match
what the other system expects.

Parameters:

 on

 of (off)

/ (a toggle between "on" and "off")

$X (any variable containing "on," "of" or "/")


Examples:

 >lf on|

 >lf /|

 >lf $X|




- MODEM CONNECT MESSAGE

Command:

 >mc [...]

("modem connect"; the command must be given in its abbreviated
form only)

Action:

Tells Flash what your modem will echo back to Flash, in
English, when another modem answers a call that your modem
makes.

Parameters:

 CONNECT

 $X (any variable containing the desired modem-connect text)


Examples:

 >mc "CONNECT"|

 >mc $X|




- MODEM FAIL MESSAGES

Command:

 >mf [... optional]

("modem fail"; the command must be given in its abbreviated
form only)

Action:

Tells Flash which of the predetermined "modem fail" messages
listed in the dial directory will echo back to Flash if a dial
command is not successful. If you do not have any "modem fail"
messages listed in the dial directory, use the "text" parameter
or the variable instead. (Or edit your dial directory properly.)

Parameters:

[none] (if no parameter is given, Flash uses the default
parameter, which is #1)

 1 (message #1 in the dial directory)

 2 (message #2 in the dial directory)

 3 (message #3 in the dial directory)

 4 (message #4 in the dial directory)

 "text" (any message, such as "BUSY")

 $X (any variable containing a modem-fail message)

Examples:

 >mf|

 >mf 2|

 >mf $X|




- EMULATION MODES

Command:

 >mo [...]

(mode)

Action:

Chooses the terminal emulation mode. The standard mode for STs
is "at" (Atari). You must match the other computer's mode.

Parameters:

 an (ansi; this lets Flash show some of the text attributes of
the ANSI standard, used by many PCs)

 at (atari; this is also called "VT52" and is a standard PC
 setting)

 vi (vidtex; a once-popular display mode that can display
graphics along with text)

 $X (any variable containing "an," "at" or "vi")

Examples:

 >mo at|

 >mo $X|




- DIALING PREFIX

Command:

 >mp [...]

("modem prefix"; the command must be given in its abbreviated
form only)

Action:

Tells Flash what text to place in front of the modem dialing
command. This is usually "ATDP" for pulse-tone (rotary dial)
lines and "ATDT" for touch-tone lines.

Parameters:

 "ATDP"

 "ATDT"

 "TEXT" (any modem dialing string prefix; capital letters are
safest)

 $X (any variable containing a dialing string prefix; capital
letters may be necessary)

Examples:

 >mp "ATDT"|

 >mp $X|




- DIALING SUFFIX

Command:

 >ms [...]

("modem suffix"; the command must be given in its abbreviated
form only)

Action:

Tells Flash what text to place after the modem dialing command.
Generally not needed.

Parameters:

"TEXT" (sometimes can be lower case)

$X (any variable containing a modem suffix; capital letters may
be necessary)

Examples:

>ms $X|




- PARITY

Command:

>py [...]

("parity"; the command must be given in its abbreviated form
only)

Action:

Sets the parity of bytes that are sent and received. By itself,
parity means little, but you should match Flash's parity with
the setting used by the other computer.

Parameters:

no (none)

od (odd)

ev (even)

$X (any variable containing "no," "od" or "ev")

Examples"

 >py no|

 >py $X|




- NUMBER OF REDIALS

Command:

 >re [...]

(redial)

Action:

Tells Flash how many times to redial a number if it receives a
"modem fail" message (if the number is busy or if for some
reason the modem can't get through). Note that a redial setting
of 1 means Flash will dial twice if necessary.

Parameters:

0-99 (any number from 0 to 99)

Example:

 >re 5|




- BACKSPACE BEHAVIOR

Command:

 >ru [...]

(rubout)

Action:

Changes the way the <backspace> key behaves during on-line
communication. With "ru" on, <backspace> deletes characters on
both screens. With "ru" off, <backspace> merely backs up the
cursor.

Parameters:

 on

 of (off)

 / (a toggle between "on" and "off")


Examples:

 >ru on|

 >ru /|




- STOP BITS

Command:

>sb [...]

("stop bits"; the command must be given in its abbreviated form
only)

Action:

Sets the number of stop bits in bytes that are sent and
received. By itself, this setting means very little, but you
should match Flash's setting with whatever the other system is
using.

Parameters:

 1

 2

 $X (any variable that contains "1" or "2")

Examples:

 >sb 1|

 >sb $X|




- STRIP BIT

Command:

 >st [...]

(strip)

Action:

Sets the "strip-bit" toggle on or off. The bit that is stripped
is the "high bit," which determines whether a character is "high
ASCII" or not. This functions only in text capture and text
send.

Parameters:

 on

 of (off)

 / (a toggle between "on" and "off")

Examples:

 >st on|

 >st /|




- BYTE LENGTH

Command:

 >wl [...]

("word length"; the command must be given in its abbreviated
form only)

Action:

Sets Flash's byte length to 7 bits or 8 bits. This is called
the word length, although it has nothing to do with English
words. Nearly all PC communication uses 8-bit byte (word)
lengths these days.

Parameters:

 7

 8

 $X (any variable containing "7" or "8")

Examples:

 >wl 8|

 >wl $X|




- Xmodem TYPE

Command:

 >xm

(Xmodem)

Action:

Determines the type of Xmodem that Flash will use, and a few
other aspects of file transfers.

Parameters:

 7 (7-bit Xmodem; rarely used any more)

 8 (8-bit Xmodem; the standard bit setting)

 C (CRC Xmodem, the preferred error-checking setting; absence
of the "C" parameter will force Flash to choose an older, less
satisfactory setting, usually called checksum Xmodem)

R ("regular" block lengths of 128 bytes K (1-kilobyte block
lengths)

 T ("Tight" timing of Xmodem block transfers, for good phone
connections)

 L ("Loose" timing of Xmodem block transfers, for poor phone
connections)

 S ("Size-byte" padding of the last block in the transmitted
file, used by Atari 8-bit systems)

 Z (Control-Z padding of the last block in the transmitted
file, the standard PC and ST method)

$X (any variable containing parameters as listed above)

Examples:

 >xm 8CKZ|

 >xm $X|




Sending and receiving files
---------------------------


Flash's primary function as a telecomm program is to send and
receive data in the form of files. Scripts make this easy.


- UPLOADING

Command:

 >ul [...] [...] [...]

(upload)

Action:

Sends a file to another computer, either from a disk or from
Flash's buffer. The upload command has either two or three
parameters -- two if you are uploading from a disk file, and
three if you are uploading from the buffer.

Parameters:

The upload command works this way if you are sending from a disk
file:

 >ul as filename.ext (for an ASCII text upload)

 >ul xm filename.ext (for an Xmodem data or text upload)

 >ul yb *.* (for a Ymodem batch upload; wildcards are needed)

The "filename" parameter can be in the form of
"filepath\filename.ext" and it can be a variable, such as "$X,"
or a string of variables, if they are used for the path and
filename.


The upload command works this way if you are sending from the
Flash capture buffer:

 >ul ca as filename.ext (for an ASCII upload of the entire
 buffer)

 >ul ca xm filename.ext (for an Xmodem upload of the entire
 buffer)


It works this way if you are sending the part of the buffer that
you have blocked off:

 >ul bl as (etc.)

 >ul bl xm (etc.)



- DOWNLOADING

Command:

 >dl

(download)

Action:

In every respect but one, the download command works the same
way as the upload command. The exception is the lack of any way
to download, using the "dl" command,to the capture buffer. (You
can, however, merely turn the capture buffer on and save all the
text that is coming across from the other computer. This is, in
effect, the same as an ASCII download.)

Here are two sample command lines:

 >dl xm filepath\filename

 >dl as $X\$Y (the variables represent the filepath and filename)




Creating and using blocks from a script
---------------------------------------


If you have used Flash's built-in text editor for more than just
reading texts, you may be familiar with its block functions.
They are readily accessed from the first four function keys
while you are using the editor (in the GEM screen). You can
easily tell when you have blocked off text in the editing
buffer, since it turns gray.

Function key 1 marks the top of a block; 2 marks the bottom; 3
clears the marks, and 4 deletes the marked block. A GEM menu bar
submenu allows you to save the marked block, and you can also
append the block to a file and upload the block.

All but one of these functions can be accessed from a DO script.
The one that does not work directly in a script is the
delete-block function. All the others can be done under control
of the script.

The typical way of manipulating text in the buffer is by turning
the capture buffer on (with the "ca on" command string), saving
the text that is entered, then clearing the capture buffer so
that you can start the process over. (This technique is used in
many of the DO file examples here.)

But there may be times when you do not want to disturb the text
in the buffer -- when you are saving all messages that come in
from a BBS, for example. Yet you may also want to save parts of
the buffer at the same time. That's where the block features
come in handy.


Here are the five block commands:

 >mk top

(mark the top of a block)

 >mk bot

(nark the bottom of a block)

 >mk cl

(clear the block

 >ap bl filename.ext

(append the block to a file)

 >sa bl filename.ext

(save the block to a file)


Here is a routine that uses block commands in a script:

>do callbbs.do|
>do sendmsgs.do|
>se "Read|"|
>ca on|
>** buffer is now saving everything|
>wa "Atari"|
>mk top|
>wa "no more messages"|
>mk bot|
>ap bl atarimsg.txt|
>mk cl|
>** saves Atari-related messages to a separate file.|
>do sendmail.do|
>do logoff.do|
>sa ca bbslog.txt|
>** saves entire capture buffer to log file.|




Setting Flash's display and sound options
-----------------------------------------


These commands control what Flash shows on the screen and what
sounds Flash makes.



- TIME SET

Command:

 >sc [...]

("set clock"; the command must be given in its abbreviated form
only)

Action:

Sets the system clock, using the 24-hour time given in the parameter.

Parameters:

 "time" (in 00:00:00 form)

Example:

 >sc 16:23:00|




- CLOCK DISPLAY

Command:

 >cl

(clock)

Action:

Displays the time in the upper right corner of the screen. The
time display is normally on unless Flash receives a "ti" (timer)
command or an "rt" (reset timer) command. In these cases, "cl"
redisplays the time.

Parameters:

 none

Example:

 >cl|




- TIMER DISPLAY

Command:

 >ti

(timer)

Action:

Changes the clock display, at the upper right corner of the
screen, to a timer. The timer is automatically set to zero every
time a connection is made, or it can be reset to zero by the
"rt" (reset timer) command.

Parameters:

 none

Example:

 >ti|




- RESETTING TIMER

Command:

 >rt

("reset timer"; the command must be given in its abbreviated
form only)

Action:

Resets the timer within Flash to zero. The timer will not be
shown on the screen unless the "ti" command is given.

Parameters:

 none

Example:

>ti|




- HIGH RESOLUTION

Command:

 >hi

(high)

Action:

Changes the monochrome-monitor to 48-line display mode. Does
nothing if a color monitor is being used.

Parameters:

 none

Example:

 >hi|




- VIEWING TEXTS OR VIDTEX GRAPHICS


 >vi [...]

(view)

Action:

Display a text file on the screen, with screen-by-screen paging
controlled by the <spacebar>. If the mode is set to "vi"
(Vidtex), this command will display a Vidtex graphic as well.
(Note that the command "vi" and the parameter "vi" are
identically spelled but have different meanings.)

Parameters:

 "filepath\filename.ext" (the optional path and optional full
filename of the text to be shown; if a wildcard is used, Flash
will display the first file it finds that matches the wildcard
specification)

 $X (any variable containing the filespec as explained above)

Examples:

 >vi c:\flash\flashdo.txt|

 >vi $X|




- BELL SOUNDS

Command:

 >b1

(single bell)

Action:

Sends a single bell sound to the monitor's speaker. It can be
repeated as often as you want, by looping the command or by
placing it many times in the script.

Parameters:

 none

Example:

 >b1|




Command:

 >b2

(repeating bell)

Action:

Sends a repeating bell sound to the speaker for about 25
seconds. If you press any key during this time, Flash stops the
bell sound and the script resumes. Otherwise, the script
resumes when the tolling stops.

Parameters:

 none

Example:

 >b2|





Setting and using directory paths and files
-------------------------------------------


These are the commands Flash uses to operate on files.


- LOADING A FILE

Command:

 >lo [...] [... optional path, mandatory filename or wildcard]

(load)

Action:

Load a file into Flash. The parameter is in two parts: The type
of file to be loaded, and the path and name of the file. The
file can be a text file loaded into Flash's text buffer using
the "ca" parameter, a configuration file loaded with the "co"
parameter, a dialing directory loaded through the "di"
parameter, a set of function-key "bindings" (key presses assigned
to function keys) loaded via the "fk" parameter, or translation
tables to change incoming and outgoing characters loaded by way
of the "tr" parameter. If you use a wildcard instead of a full
filename, Flash will load the first file that matches the
wildcard. CHECK THIS.

Parameters:

(Note: If you do not specify the location of the file to be
loaded, Flash looks for it in the default folder, the one Flash
was executed from.)

 ca d:\filepath\filename.ext (any drive and folder path)

(capture buffer)

 co d:\filepath\filename.ext

(configuration file; the default is FLASH.CNF, but you can name
other configuration files any name you choose)

 di d:\filepath\filename.ext

(dialing directory; the default is FLASH.DIR, but you can name
other dialing directories anything you wish)

 fk d:\filepath\filename.ext

(function-key assignments; the default is the wonderfully named
FUNCKEY.DEF, but you can use any other name for optional
function-key loaders)

 tr d:\filepath\filename.ext

(translation tables; FLASH.TRN is the default, but any name is
OK for optional tables)

 [...] $X

(any variable containing d:\filepath\filename.ext)

Examples:

 >lo ca c:\flash\messages.txt|

 >lo ca $X|

 >lo di c:\flash\localbbs.dir|




- SAVING A FILE

Command:

 >sa [...] [... optional path, mandatory filename]

(save)

Action:

Save a file into Flash. The parameter is in two parts: The type
of file to be loaded, and the path and name of the file. The
file can be a text file saved from Flash's text buffer using the
"ca" parameter, a configuration file saved with the "co"
parameter, a dialing directory saved through the "di" parameter,
a set of function-key "bindings" (key presses assigned to
function keys) saved via the "fk" parameter, or translation
tables to change incoming and outgoing characters saved using
the "tr" parameter.

Parameters:

(Note: If you do not specify the location of the file to be
saved, Flash saves it in the default folder, the one Flash was
executed from.)

 ca d:\filepath\filename.ext (any drive and folder path)

(capture buffer)

 co d:\filepath\filename.ext

(configuration file; the default is FLASH.CNF, but you can name
other configuration files any name you choose)

 di d:\filepath\filename.ext

(dialing directory; the default is FLASH.DIR, but you can name
other dialing directories anything you wish)

 fk d:\filepath\filename.ext

(function-key assignments; the default is FUNCKEY.DEF, but you
can use any other name for optional function-key loaders)

 tr d:\filepath\filename.ext

(translation tables; FLASH.TRN is the default, but any name is
OK for optional tables)

 [ ] $X (any variable containing d:\filepath\filename.ext)

Examples:

 >sa ca a:\messages.txt|

 >sa ca $X|

 >sa fk c:\flash\fkey\funckey2.def|




- CHANGING A DIRECTORY PATH

Command:

>cd [...]

(change directory; the command must be given in its abbreviated
form only)

Action:

Tells Flash to look in the specified path for all files and to
use that path when saving files unless another path is specified
in individual commands. Note: This command is identical to "dp".

Parameters:

 d:\filepath\filename.ext

 $X (any variable containing a path and filename)

Examples:

(Note that the trailing slash is necessary.)

 >cd c:\flash\|

 >cd $X|




- SETTING A DEFAULT DIRECTORY

Command:

>dp [...]

(default path; the command must be given in its abbreviated
form only)

Action:

Tells Flash to look in the specified path for all files and to
use that path when saving files unless another path is specified
in individual commands. Note: This command is identical to "cd."

Parameters:

 d:\filepath\filename.ext

 $X (any variable containing a path and filename)

Examples:

(Note that the trailing slash is necessary.)

 >dp c:\flash\|

 >dp $X|




- CHECKING DISK SPACE

Command:

 >df [... optional]

(disk free)

Action:

Displays the amount of free space on the default drive, or, if
a filepath is given, on that drive. Note that the first two
parameter examples listed below accomplish the same thing.
Flash will not show the free space in a folder per se, since
folders can hold as much as the entire drive they are on, minus
a little overhead.

Parameters:

 d:

 d:\filepath\

 $X (any variable containing a drive specifier)

Examples:

 >df c:|

 >df $X|




- LISTING FILES IN DIRECTORY

Command:

 >dd [... optional] [... optional]

(disk directory)

Action:

Lists the folders and files in the filepath specified as the
first parameter, or in the default path if no specification is
given. The list is written to the screen as the default, but it
can also be written to a disk file or sent out the modem port.

Parameters:

Note: The trailing slash is required.

 d:\filepath\filename.ext (any filepath; wildcards are allowed
for the filename)

 d:\filepath\*.* AUX: (sends the list to the modem, the "AUX:"
device on the ST; a space is needed in front of "AUX:")

 d:\filepath\*.* filename.ext (writes the list to a disk file)

Examples:

 >dd|

 >dd AUX:|

 >dd c:\flash\*.txt|

 >dd a:\dofiles\*.*

 >dd c:\bbstexts\local\numbers.* AUX:|

 >dd c:\flash\do\*.do dolist.txt|


- OPENING A FILE

Command:

 op [...]

(open)

Action:

Opens a disk file, using a standard filespec, or the Flash
capture buffer, using "BUF:", to check or read the  data, or
opens the modem port, using "AUX:". Flash can be instructed to
report on whether the operation was successful. In other words,
Flash can test to see if a particular file exists -- or even any
file at all exists, with wildcards -- using the "op" command.
The "op" command is tested by issuing an "if" command followed
by a tilde (the "~" character) in front of "op". See the context
examples below for the use of "op" with files. The function of
"op" with "BUF:" and "AUX:" is covered in "Making better use of
the capture buffer" below.

Parameters:

 d:\filepath\filename

 d:\filepath\*.*

 BUF:

 AUX:

 $X (any variable containing a filespec, "BUF:" or "AUX:")

Examples:

 >op c:\wordproc\feblettr.txt|

 >op a:\dofiles\*.do|

 >op BLK:|

 >op BUF:|

 >op $X|


Context examples:


>op c:\flash\messages\bbsdaily.txt|
>if ~op sa ca c:\flash\messages\daily.txt|
>**

Checks to see if the daily message file exists.  If it does not
exist, Flash saves the contents of the capture buffer to a new
file of that name.

|


>op a:\errorlog.txt|
>if ~op jmp noerrors|
>vi a:\errorlog.txt|
>L: noerrors|
>**

Checks for the presence of an error log and displays it on the
screen if found.

|




- KILLING A FILE

Command:

 >ki [...]

(kill)

Action:

Kills (deletes) a file. The parameter can include a filepath as
well as a filename, and can include wildcards. If wildcards are
used, Flash deletes the first file it finds that matches the
wildcard specification. Multiple deletions can be made by
issuing the "ki" command with a wildcard parameter, checking to
see if any files still exist in the path using the "op" command,
and looping back through those two commands until the "op"
command does not find a file. See the context example below.

Parameters:

 d:\filepath\filename.ext

(kills a single file in that folder)

 d:\filename

(kills a single file in the root directory of d:)

 d:filename

(kills a single file in the default directory; the "d:" can be
omitted)

 d:\filepath\*.txt

(kills the first file it finds in that directory having a ".txt"
extender)

$X (any variable containing a filespec)

Examples:

 >ki a:\oldmsg.txt|

 >ki c:\flash\*.bak|

 >ki $X|


Context examples:

** Killing all files in a pathway using wildcards **

>L: filekiller|
>ki c:\flash\oldfiles\*.*|
>op c:\flash\oldfiles\*.*|
>if op jmp filekiller|
>**

If Flash cannot open any file matching the wildcard spec, the
loop is broken. Otherwise, it continues to delete files.

|




** Killing selected files using wildcards **

>L: filekiller|
>ki c:\flash\oldfiles\*.txt|
>op c:\flash\oldfiles\*.txt|
>if op jmp filekiller|
>**

If Flash cannot open any file matching the wildcard spec, the
loop is broken. Otherwise, it continues to delete files.

|




Using the capture buffer from a DO script
-----------------------------------------


Flash's capture buffer is more than just a place to store text.
It can be used to manipulate text, and it can even be used to
make copies of program files and data files, in addition to text
files.


- TURNING THE CAPTURE BUFFER ON AND OFF

Command:

 >ca [...]

(capture)

Action:

Turns the capture buffer on or off. Note: Turning the capture
buffer off does not affect anything already in the buffer; it
merely shuts the buffer so that nothing is added.

Parameters:

 on

 of (off)

\ (a toggle between on and off; this is not a satisfactory way
of handling the capture buffer in a script, since you may not be
able to control which setting is being switched)

Examples:

 >ca on|

 >ca of|

 >ca \|




- CLEARING THE BUFFER

Command:

 >cl

(clear)

Action:

Clears the capture buffer. Everything is removed, whether the
buffer is on or off at the time.

Parameters:

 none

Example:

 >ca cl|




- LOADING THE BUFFER

Command:

 >lo ca [...]

(load capture)

Action:

Loads a file into the capture buffer from the filespec given as
the parameter. This command is also listed above, under "lo".

Parameters:

 d:\filepath\filename.ext

 $X (any variable containing a filespec)

Examples:

 >lo ca a:\bixmsgs.txt|

 >lo ca $X|




- SAVING THE BUFFER

Command:

 >sa ca [...]

(save capture)

Action:

Saves a file from the text in the capture buffer to a disk file
using the filespec given as the parameter. This command is also
listed above, under "sa".

Parameters:

 d:\filepath\filename.ext

 $X (any variable containing a filespec)


Examples:

 >sa ca a:\bixmsgs.txt|

 >sa ca $X|




- MARKING A BLOCK WITHIN THE BUFFER

Command:

 >mk [...]

(mark)

Action:

The "mk" command is awkwardly specified. Depending on the
parameter chosen, it marks the top or the bottom of a block in
the capture buffer or clears the mark(s). The block can then be
saved or placed at the end of (appended to) a disk file.

Parameters:

 top (the beginning of a block of text)

 bot (the end of a block of text)

 cl (clear any marks)


Examples:

 >mk top|

 >mk bot|

 >mk cl|




- APPENDING A MARKED BLOCK TO THE END OF A FILE

Command:

 >ap bl [...]

(append block)

Appends the marked block to a disk file (places it at the end
of the file).

Parameters:

 d:\filepath\filename.ext

 $X (any variable containing a filespec)


Examples:

 >ap bl c:\flash\filelist.txt|

 >ap bl $X|




Executing programs within Flash
-------------------------------


Unlike no-frills telecommunications programs, Flash is able to
run other programs within Flash. They can be GEM programs, which
use the mouse and have GEM menus, or they can be either of the
two types of TOS programs -- regular TOS ("The Operating
System") or TTP ("TOS - Takes Parameters").


- RUNNING A GEM PROGRAM

Command:

 >gem [...]

(run a GEM program)

Action:

Executes a GEM program. The new program takes over and Flash
disappears. When the program ends, Flash reappears. You can
safely run all types of GEM programs *except* other
telecommunications programs, since Flash still has control of
the modem port even when it is running another program.
However, you can run programs that support telecomm functions,
such as an external Zmodem module.

If Flash's capture buffer was turned on when the GEM program is
launched, you may find that Flash will still try to store
incoming data from another computer while the GEM program is
running. However, this can lead to system crashes and other
unexpected behavior unless the GEM program was designed to allow
Flash to do this.

Parameters:

 d:\filepath\filename.ext

 $X (any variable containing a filespec)


Examples:

 >gem c:\bin\wordperf\wp.prg|

 >gem $X|



- RUNNING A TOS OR TTP PROGRAM

Command:

 >exec [...] [... optional]

(execute)

Action:

Executes a TOS or TTP program. The new program takes over and
Flash disappears. When the program ends, Flash reappears. You
can safely run all types of TOS and TTP programs *except* other
telecommunications programs, since Flash still has control of
the modem port even when it is running another program. However,
you can run programs that support telecomm functions, such as an
external Zmodem module.

If Flash's capture buffer was turned on when the TOS or TTP
program is launched, you may find that Flash will still try to
store incoming data from another computer while the TOS or TTP
program is running. However, this can lead to system crashes and
other unexpected behavior unless the TOS or TTP program was
designed to allow Flash to do this.

Parameters:

In addition to the usual filespec parameter, TOS programs can
also accept command-line switches; TTP programs *must* have
command-line parameters and switches. (Their name, "TOS - Takes
Parameters," indicates the need for such command-line
parameters.) The most common parameters and switches may be
found in archivers such as ARC.TTP and LHARC.TTP, which need to
have the name of the file to be archived or extracted, along
with any other instructions. Usually, the only valid
command-line parameter for TOS programs is a filename.

 d:\filepath\filename.ext [command-line parameters and switches]

 $X (any variable containing a filespec and optional switches)

Examples:

 >exec c:\STWriter\STWriter.tos mytext.stw|

 >exec c:\archives\lharc.ttp -x thisfile.lzh|

 >exec $X|



- A SPECIAL CASE: THE ARC COMMAND

Flash has an "exec" command that operates only on a file named
ARC.TTP. It's the "arc" command. It is an alias for the "exec
arc" command string. Although the official Flash documentation
makes no reference to this, you could name *any* .TTP program
"ARC" and run it this way (although why you would want to would
not be obvious).



Other commands
--------------


- PUTTING FLASH ON HOLD

Command:

 >pa [...]

(pause)

Action:

Halts all activity for the number of seconds specified in the
parameter.

Parameter:

 # (number of seconds)

Examples:

>pa 3600|

>pa 1|



- SENDING A FORM FEED TO THE PRINTER

Command:

 >ff

(form feed)


Action:

Sends the printer a form feed (ejects or rolls up the current
page). If the printer is not turned on, Flash will wait and
then continue the script execution.

Parameters:

 none

Example:

 >ff|



- ENDING A ROUTINE OR THE ENTIRE SCRIPT

Command:


 >end

(end the script)

Action:

Stops the DO script. If the script was run from another script,
Flash returns to the calling script at the next command in that
script. You may have more than one "end" command in a script if
you are using subroutines that need to be dead-ended. However,
you may find it easier to debug a long script that has such
subroutines if you use a "jmp" command at those points to bring
all subroutines to a common exit point.

Parameters:

 none

Examples:

 >end|

 >L: label_1|
 >ifi $A "failure" jmp main_exit|
 >ifi $A "no call" jmp main_exit|
 ...
 >L: main_exit|
 >end|




- QUITTING FLASH

Command:

 >xd

(exit to the desktop)

Action:

Stops the DO script and forces Flash to quit. All variables
that had been set will be lost when Flash ends unless you save
them. Use SAVEVARS.DO, included with this documentation, to
save variables before the "xd" command is executed.

Parameters:

 none

Examples:

 >xd|

 >L: quit_to_desktop|
 >do savevars.do|
 >xd|



- MAKING FLASH DO SOMETHING ON STARTUP

Command:

 >au

(auto startup command)

Action:

Places a command in Flash's memory that will be executed before
any other commands when Flash loads -- but only if you save
Flash's configuration file before quitting that session of
Flash. (See example below.) You can have multiple commands, if
they are properly separated.

Parameters:

 [any command] [any filespec]

(The parameters that follow the "au" command cannot be longer
than 19 characters long, including spaces.)

Examples:

 >au do makevars.do|

(runs MAKEVARS.DO on startup, to restore variables)


 >au vi c:\help.txt|

(shows a help file as soon as Flash runs)


 >au ty Hello!|

(types "Hello!" on the screen when Flash runs)


 >au b2|>menu|

(rings a bell, then shows the Flash GEM menu when Flash runs)



- GETTING HELP

Command:

 >he

(help)

Action:

Drops Flash's Help window down on the screen and halts script
execution while the Help window is shown. The Help window will
stay there forever if you do not remove it manually, so do not
use this command in a script that runs unattended. Pressing the
[undo] key removes the Help window.

Example:

 >he|



- ACTIVATING THE PRINTER

Command:

 >pr [...]

(printer)

Action:

Echoes text that is being captured from the modem port to the
printer port. If the printer is not on, Flash will continue
execution anyway. Consider a printer buffer (a software buffer
such as the Codehead SPOOLER.PRG or a hardware buffer) if you
plan to use the "pr" command often, since Flash can take input
from the modem port much faster than most printers can print. A
slow printer can force Flash to pause unduly.

Parameters:

 on

 off

 / (a toggle between on and off; not useful in scripts because
 the prior state of the "pr" command may not be predictable)


Examples:

 >pr on|

 >pr off|

 >pr /|



- FREEING MEMORY FOR OTHER PROGRAMS

Command:

 >fr [...]

(free)

Action:

Frees a portion of the computer's memory for use by another
program. This is especially handy if you have a desk accessory
that refuses to run because it found insufficient memory. Memory
that has been freed cannot be "unfreed" back to Flash. Please
note that if you free up too much memory, Flash's capture buffer
will shrink to an unusable size.

Parameters:

 # (any number, representing the number of kilobytes of memory
freed from Flash)

Examples:

>fr 200|

>fr 0060|

>fr 1024|



- SETTING UP THE TYPE-AHEAD BUFFER

Command:

 >ta

(type ahead)

Action:

Changes Flash's command line into a one-line type-ahead buffer.
Note: Previous type-ahead lines can be brought back from
Flash's memory by using the up-arrow key.

Parameters

 none

Example:

 >ta|



- OPENING THE STATUS DISPLAY WINDOW

Command:

 >ss

(status)

Action:

Opens the full-screen window of Flash's status display. While
most of the configuration shown in the status window is
duplicated in GEM menus, there are some that are shown only in
the status window. The "au" (auto) command status is one of
them. The only way to see if the copy of Flash that is running
has an auto instruction is to open the status window.

Parameters:

 none

Example:

>ss|






P A R T   5 :  A D V A N C E D   F L A S H   C O M M A N D S
------------------------------------------------------------





- ALERTING THE USER AND ASKING FOR A PRE-PROGRAMMED RESPONSE

Command:

 >al [...]

(alert box)

Action:

Places a GEM alert box on the screen and pauses for mouse or
keyboard response to one, two or three brief choices. The alert
box can have one, two or three boxed choices called radio buttons
(mutually exclusive choices, like the station buttons on a car
radio), and those buttons can contain numbers or text. The area
above the buttons can have one, two or three lines of text. The
alert command can be written to provide a keyboard shortcut for a
default choice; the default button, if any, is surrounded by a
thick box, and can be chosen pressing [return]. However, the
mouse can always be used to click on one of the buttons whether
or not a default is given.

Parameters:

 "[#][text1|text2|text3][button text1|text2|text3]" $X #

The parameters must have quotation marks and brackets as shown.
They are divided into sections. The first is the icon type, if
any, that is displayed within the alert box. Icon 0 is no icon,
1 is an exclamation mark, 2 is a question mark and 3 is a stop
sign. Any single digit less than 1 or greater than three equals
no icon.

The second section, also in brackets, can be divided into three
parts. It is the text of the alert box, with the "|" symbol
marking the end of line 1 and line 2. (Line 3 does not need the
"|" symbol.) You may have, at most, 30 characters (including
spaces) in two of the parts; the third can't have more than about
25 or so depending on what else is in the alert box. (The alert
command must be contained on one line. Flash can't handle a
command line more than 96 characters wide, including the command
itself, the space after the command, the "|" at the end and the
parameters in between.) Play around with sample alert boxes to
see how much you can place in the box safely before you write any
alerts for normal scripts.

The third section, placed within brackets also, contains the
button texts. You must have at least one button, although the
"text" can be blank or can be a graphic character from the ST/TT
keyboard, such as a [control-B] character. The maximum length
of a button text is 10 characters.

The variable ($X in the generic example above) can be any letter,
uppercase or lowercase, and is optional. If a variable is
present, the text in the button that the user selects will be
placed in the variable. Note that if you do NOT use a variable,
the action of the last section is unpredictable.

The last section, which is optional, should be "1", "2" or "3".
It controls which button becomes the default -- the one that
automatically will be selected if the user presses [return]. If
you use "0" or a number greater than 3, Flash does not act in a
predictable manner; Flash will either provide no default button
or will make one of the buttons the default based on which button
was used as a default the last time an alert box was shown.

Examples:

 >al "[1][File exists.|Overwrite it anyway?][Yes|No]" $A 2|

 >al "[2][Choose a drive|to save the file to.][A:|B:|C:]" $X 1|

 >al "[3][WARNING!|Modem is not responding!][OK|QUIT]" $M 2|




- GETTING ANY TEXT STRING FROM THE USER

Command:

 >qu [...]

(query)

Action:

Shows an alert box that prompts the user for up to 40 characters
of input from the keyboard. The box can contain a short text of
up to three lines that gives instructions for the user. This
text is the first parameter of the command.

The input is placed in a variable, the second parameter. The
user input can include ST/TT graphics characters in addition to
letters and numbers.

Parameters:

The two parameters are the text of the query and the variable to
place the input in. Although the query box is large enough to
contain a lot of text, Flash's limit on the length of command
lines will keep you from writing more than about 90 characters.
Each line of text can be up to 40 characters long and must end
with a "|" symbol, and the entire text must be in quotes.

Examples:

 >qu "Please type your full name:" $N|

 >qu "What BBS telephone number|do you want to call?" $X|

 >qu "Please type the password|for access to this script:" $P|




- COMBINING USER INPUT WITH STRING MANIPULATION

Context examples:

1. A simple request for a number to dial.

The variable "X" is checked to make sure it is not blank, and
the contents of the variable are then passed to the dialing
command. This routine makes no attempt to check to see if the
contents of the variable are indeed numbers; this can be done in
Flash, but only with a great deal of effort. (A partial example
of how to do that is shown below.)


>L: getnumber|
>qu "What BBS telephone number|do you want to call?" $X|
>if ~X jmp getnumber|
>ty You typed: $X.|
>ty|
>ty Dialing $X...|
>ty|
>di #$X|


2. A way to check for numbers in a variable.

Flash does not have any method of treating variables as numerics
instead of simple text strings, so you need to check for the
presence of at least ONE number with a routine like this:

>L: getnumber|
>qu "What BBS telephone number|do you want to call?" $X|
>if ~X jmp getnumber|
>ifi $X "0" jmp ok|
>ifi $X "1" jmp ok|
>ifi $X "2" jmp ok|
>ifi $X "3" jmp ok|
>ifi $X "4" jmp ok|
>ifi $X "5" jmp ok|
>ifi $X "6" jmp ok|
>ifi $X "7" jmp ok|
>ifi $X "8" jmp ok|
>ifi $X "9" jmp ok|
>ty You did not type a number!|
>ty|
>jmp getnumber|
>L: ok|
>ty You typed: $X.|
>ty|
>ty Dialing $X...|
>ty|
>di #$X|


3. A way to make sure two variables are exactly the same.

In one of the examples above, the user is asked for a password.
The standard method of checking one variable against another is
the "ifi" command ("ifin" -- meaning "if the contents of this
variable are contained in the other one"). But "ifi" checks only
for a non-exclusive match; Flash just checks to see if the string
in one variable is *included* in the other one.

In other words, a variable containing the string "John" will
pass an "ifi" comparison against a variable containing the string
"Johnson" and a variable containing the string "Johnny on the
Spot." If you want to make an exact match, you have to resort to
some string manipulation.

That's not puppet talk; it's the way you can turn a text string
entered by the user into something else. The easiest way is to
add front and back delimiters to the string. They mark the
beginning and the end, so you can compare another string for an
exact match for content and length.

Here's how that's done. In the example below, variable X takes
over from variable P for password checks. The actual password is
stored in a file called PASSWORD.DAT, which consists of all the
passwords, one to a line. The "inp" command reads each line of the
PASSWORD.DAT file into a variable, and that variable is checked
against the user input. (Note that the user gets only a few
chances to type the password right. This is done by a loop that
increments a counter. When the counter reaches as certain value,
the routine bounces the user out of the script.)

>L: start|
>$C 0|
>jmp getpw|
>L: RetryLoop|
>ifi $C "0" jmp increment0|
>ifi $C "1" jmp increment1|
>ifi $C "2" jmp increment2|
>ifi $C "3" ty Too many failures! Script aborted.|
>ifi $C "3" end|
>L: getpw|
>qu "Please type the password|for access to this script:" $P|
>if ~P jmp getpw|
>$X &$P&
>** The user string now begins and ends with the "&".|
>op password.dat|
>if ~op ty Password data corrupted! Please run SETUP.DO!|
>if ~op end|
>L: InputLoop|
>inp $A|
>if eof jmp NotFound|
>** If the end-of-file mark is reached before a match is made,|
>** the password is not there.|
>$B &$A&|
>ifi $B $X jmp pwOK|
>jmp InputLoop|
>** password not found routine|
>L: NotFound|
>ty Password not found. Please notify the system programmer.|
>ty|
>end|
>** counter increment routine|
>L: increment0|
>$C 1|
>jmp getpw|
>L: increment1|
>$C 2|
>jmp getpw|
>L: increment2|
>$C 3|
>jmp getpw|
>** password ok routine|
>L: pwOK|
>ty Password accepted. Launching script...|
>ty|
>do anyscript.do|
>end|




Handling text input and text strings
------------------------------------



- GETTING REMOTE INPUT

Command:

 >ge [...]

(get)

Action: Gets a text string from the other computer across the
modem port. The maximum length of the string is a little over
100 characters. It's important to note that the "ge" command
recognizes a carriage return as the end of the string, but does
not include it in the string that it saves in Flash's input
buffer. This means that a bare carriage return sent from the
other computer will be interpreted as an empty string. Flash
*can* find empty strings, however, as we shall see below.

Parameters:

 $X (any variable)

Example:

>ge $B|

Context example:

>se "Please type your name.|"|
>ge $N|




- CHECKING FOR THE SPECIFIC CONTENTS OF A VARIABLE

Command:

>ifi [...] [...] [...]

(ifin)

Action:

Looks at a text string contained in a variable to see if there
is a matching string. If it finds one, Flash executes the
command given after the string comparison. The string does not
need to be a complete match for the full text of the variable's
string; all Flash does is check for its inclusion (thus the name
"ifin" in the full spelling of this command, which means "if in
string X you find string Y, you've got a match").

This means that the string "Harry" is contained in the string
"Harry's Bar and Grill," as is the string "ar" (in fact, it is
in there twice). But the string "Harry's Bar and Grill" is *not*
contained in the string "Harry". Be careful to place your
comparisons properly so that the strings are compared the way
you want them to be. The "ifi" command always works in this
order: If in string 1 is string 2, execute a command.

Flash does not check for the case of the string characters in
the comparison. "The" is the same as "the" and "tHe" and so on.


Parameters:

 First parameter: $X (any variable)

 Second parameter: $X (any variable) or any text string

 Third parameter: any Flash command


Examples:

>ifi $X "Yes" jmp showmenu|

>ifi $Y "Monday" al "[1][Do weekly backups?][Yes|No]" $Z 1|


Context example:

>L: top|
>qu "Type the name of the script:" $X|
>ifi $X ".do" jmp nameOK|
>al "[3][""DO"" extender missing!Try again?][Yes|No]" $Y 1|
>ifi $Y "Yes" jmp top|
>do $X|



- TESTING FOR EMPTY VARIABLES AND SUCCESSFUL COMMANDS

Command:

 >if [~] [...] [...]


Action:

The "if" command is quite powerful. In essence, it tests a
condition. One use is to test a variable.

Tests for *any* string in a variable, or for a null in a
variable. The first parameter (or, more properly, a command
switch) is the "~" symbol, which inverts the command, so that it
checks for a null.

A null is an empty variable, also called an empty string. You can
create a nulled variable yourself, or a variable can become
nulled if Flash is waiting for user input and receives only a
carriage return.

Unlike all other Flash commands that use variables, the "if"
command is *not* followed by the "$X" designation of a variable,
but only by the character representing the variable, without the
dollar sign. Thus you have "if X" and *not* "if $X".


Parameters:

 Optional switch: ~ (turns "if" to "if not")

 First parameter: X (any variable, without the "$")

 Second parameter: any Flash command


Examples:

>if X se "Thanks for the response!|"|

>if ~D ty Date not set.|


Context example:

>L: top|
>se "Please type your name.|"|
>ge $N|
>if ~N se "You must type your name.|"|
>if ~N jmp top|
>se "You typed: $N.|"|
>se "Is this correct? (Y/n): |"|
>ge $C|
>if ~C se "Sorry, we must log you off...|"|
>if ~C hg|
>ifi $C "Y" jmp nameOK|
>jmp top|



The other uses of the "if" command test for the successful
completion of a command or a condition. The commands all use
"if" the same way, with the "~" used to invert the meaning.

Not all commands or conditions can be tested; here are the ones
that are included:

ca (carrier; checks for presence of modem carrier)
>if ca [command]
>if ~ca [command]

di (dial; checks for completion of dial command)
>if di [command]
>if ~di [command]

eof (end of file; used when inputting data)
>if eof [command]
>if ~eof [command]

op (open; checks for presence of a file)
>if op [command]
>if ~op [command]

ul (upload; used to tell if an upload was OK)
>if ul [command]
>if ~ul [command]

wa (wait for a string; checks if the string was found)
>if wa [command]
>if ~wa [command]




Simple examples of The "if" command
-----------------------------------


Usually, the "if" command is thought of as essential for remote
DO scripts -- those that run while you are asleep, for example,
as you might want to do when calling a long-distance BBS or a
busy telecomm service.

But it can also be very useful in scripts that are running when
you are at the console. The "if" command can be made to check on
a number of things that your computer can do better (or at least
faster) than you can.

Here is a simple dialing routine using "if" with the "di"
command:

>L: makecall|
>di #123-4567|
>if ~di al "[1][Dial failed!|Try again?][Yes|No]" $X 1|
>ifi $X "Yes" jmp makecall|


Here is a routine that makes sure your modem still has a carrier
before it tries an upload or download:

>if ca ul myfile.ext|


Here is a way to make Flash repeat an upload attempt if
necessary. It also checks for a carrier and checks to see if the
"wa" command failed:

>L: makeupload|
>se "U|"|>** upload command sent to a BBS.|
>wa "Ready"|>** wait for string from BBS.|
>if ~wa jmp warning|
>if ca ul myfile.ext|
>if ~ul jmp tryagain|
>end|
>L: tryagain|
>pa 5|>** pause for any length of time to let BBS react.|
>se "U|"|
>wa "Ready"|
>if ~wa jmp warning|
>if ca ul myfile.ext|
>if ~ul jmp warning|
>end|
>L: warning|
>al "[3][Upload attempt failed!|Try again?][Yes|No] $Y 2|
>ifi $Y "Yes" jmp makeupload|
>end|




Checking to see if a file exists
--------------------------------


The "op" (open) command has two primary uses when dealing with
disk files. The first is to open a file so that the contents can
be read line-by-line. We'll get to that shortly, but we should
first see how "op" can be used to do nothing more than confirm
that a file exists. This is done through the "if" command. Here
is an example:

>op myfile.ext|
>if op al "[1][File exists!|Overwrite it anyway?][Yes|No] $X 2|
>ifi $X "Yes" sa ca myfile.ext|


The same technique can be used to see if a folder exists. Flash
cannot see folders that way it can see files, but that shouldn't
get in the way if you intentionally test for the presence of a
folder by trying to save a file to that folder. Here's an
example, which uses the "log" command to create a small text
string in the capture buffer and then tries to save that string
to a file:

>$X|>** Var. X is nulled so it can be used below.|
>ca on|
>ca cl|
>log "This is a string of test data.|"|
>sa ca foldname\test.dat|>** any folder name can be used.|
>op foldname\test.dat|
>if ~op al "[1][Folder does not exist!][Sorry!]" $X 0|
>ifi $X "Sorry" end|
>al "[1][Folder located!][Thanks!]" $X 0|
>ca cl|
>end|


A routine like the one above could get a lot fancier. The only
thing Flash cannot do unaided is create a folder. It can easily
find any folders, however, so it wouldn't hurt to make sure you
have various folders already created, even if they are empty.




Getting Flash to read data from a file
--------------------------------------


Reading data from a file is a good way of making Flash check the
contents line-by-line. The process actually goes fairly quickly
if the file is read from a fast hard disk or from a ramdisk. If
your computer has a lot of memory, you can make the process even
faster by loading the data file into the capture buffer and
reading each line from the buffer.

Please note that the data file should be a *formatted* text
whenever possible -- in other words, a file just like the one
you are reading, with lines that do not exceed the screen width.
Lines that are longer than about 90 characters are truncated by
Flash (the ends are cut off), which will keep Flash from seeing
whatever was located past that point on each line.

Why would you want to have Flash read a data file? There are
quite a few good reasons. If you regularly run a DO script (or a
series of scripts) while Flash is running unattended, you may
want to have Flash save an error.log to disk. Later, Flash can
automatically check the error.log for various entries, alerting
you if it finds some that are serious problems.

A sexier use might be to have Flash automatically read a message
file for certain key words. In other words, you could create a
script that turns Flash into a sort of database manager,
alerting you to text files that you may want to read (and saving
you the trouble of paging through text files that aren't worth
reading).

The basic routine that you *must* (and I mean *must*!) use
follows this pattern:

>op filename.ext|
>if ~op end|
>L: looptop|
>in $X|
>if eof jmp loopend|
>ifi $X "target string" jmp loopend|
>jmp looptop|

First you must open the file. Then you must have a label at the
top of the input loop. The next command must be the "in" (input)
command, using a variable to store the data. The very next
command *absolutely must* be a check for the end-of-file marker;
otherwise, your loop could go on forever. The next line uses the
"ifi" (ifin) command to check for the presence of the string you
are looking for in the data file. If the string is not found,
Flash loops back to the top and inputs the next line and starts
the search again.

You can, of course, have Flash search for more than one target
string. Obviously, with 26 possible variables, you can specify
26 separate target strings. It's even possible to search for
more than 26, by manipulating the strings. (I'll let you work
that out for yourself as a little challenge. Write to me if you
manage it in a clean fashion -- no thousand-line DO files,
please!)

Here's the same routine as the one above, with multiple target
strings:


>op filename.ext|
>if ~op end|
>L: looptop|
>in $X|
>if eof jmp loopend|
>ifi $X "target string 1" jmp loopend|
>ifi $X "target string 2" jmp loopend|
>ifi $X "target string 3" jmp loopend|
>ifi $X "target string 4" jmp loopend|
>ifi $X "target string 5" jmp loopend|
>ifi $X "target string 6" jmp loopend|
>jmp looptop|


After you've set up Flash to check for target strings in a data
file, what do you do with them? You'll need to create another
routine, or perhaps a separate DO script, to process the
information that Flash picked up from the data file. In the
example below, I'll assume that you want Flash to check the
current message download from a BBS for any mention of the ST,
the TT or Atari. This will be a rudely basic example, and you'll
probably want to make it a lot more specific.

First, here's a tip on how to make sure Flash finds the
character strings you are really looking for. The precise string
you are looking for should be delineated in some way, probably
by placing a space in front of and behind it. For example, if you
want Flash to find the string "ST" in the data file, you should
list that string twice in your "in" command -- once with a space
in front of it, and once with a space behind it. This will keep
Flash from finding the two letters "st" within such words as
"fast" or "stupid" (I know, who would dare put the word "stupid"
in a BBS text file? But you never know....)

Once the file has been checked, you should branch to a routine
that makes use of the variables. This is what we'll be doing
below.

(In this routine, the string "Atari" is specific enough, so we
won't place spaces around it.)


>$S|
>$T|>** These must be nulled at the start.|
>$A|
>op bbsmsg.txt|
>if ~op end|
>L: looptop|
>in $X|
>if eof jmp loopend|
>ifi $X " ST" jmp st_found|
>ifi $X "ST " jmp st_found|
>L: tt_search|
>ifi $X " TT" jmp tt_found|
>ifi $X "TT " jmp tt_found|
>L: atari_search|
>ifi $X "Atari" jmp atari_found|
>jmp looptop|
>L: st_found|
>$S the ST|
>jmp tt_search|
>L: tt_found|
>$T the TT|
>jmp atari_search|
>L: atari_found|
>$A Atari in general|
>L: loopend|
>if S jmp combine_vars|
>if T jmp combine_vars|
>if A jmp combine_vars|
>$B No mention of the ST, the TT or Atari in general found.|
>jmp store_B|
>L: combine_vars|
>if ~A jmp no_A|
>if ~T jmp no_T|
>$B Search found mentions of $S, $T and $A.|
>jmp store_B|
>L: no_A|
>if ~T jmp no_T|
>$B Search found mentions of $S and $T.|
>jmp store_B|
>L: no_T|
>$B Search found mentions of $S.|
>L: store_B|
>ca on|
>ca cl|
>log $B|
>log|
>sa ca msgalert.dat|
>ca cl|
>vi msgalert.dat|
>** msgalert.dat is shown on the screen.|
>end|


You could try many varieties of the script above. One variation
would be to have Flash show you each line of text that contains
the target string(s). All you'd need to add to do that are these
two lines right after the "xx_found" labels:

>ty $X
>ty|


Or you could place all the lines of text that contain the target
strings into Flash's buffer, and then save the buffer. To do
that, use this line in place of the two lines above:

>log $X|

and then save the capture buffer when the loop is finished.




Using a data file to check your drives
--------------------------------------


By writing a script that does nothing except write a line of
data to a file, you can have Flash try to open the file on each
drive in your computer's system. Files that fail to open don't
exist -- and that means there must be some sort of trouble with
the drive. Here's an example:


>ca on|
>ca cl|
>log This is a line of test data.|
>sa ca a:\test.dat|
>op a:\test.dat|
>if ~op al "[1][Trouble with Drive A:!][Thanks!]" $X 0|
>sa ca b:\test.dat|
>op b:\test.dat (etc..)






P A R T   6 :  F L A S H ' S   H I D D E N   F E A T U R E S
------------------------------------------------------------





Flash has a file copier -- and it's not just for texts
------------------------------------------------------


Flash's text storage area is called the capture buffer. Any time
you type something into the text editor, you are using the
capture buffer. You can also load a text from a disk file into
the capture buffer, and of course you can save text that is
coming across the modem port into the buffer.

The "sa" (save) command allows you to save whatever is in the
capture buffer to a disk file. Since the capture buffer is used
by the text editor, most users probably assume that they cannot
use the capture buffer to hold program files. And few may have
understood that the capture buffer can also be used to copy
software.

In other words, you can load a binary file (a program) -- not
just a text file -- into the capture buffer and then save the
buffer to another location. If you have a large enough capture
buffer, you can use it to copy even very large programs.

I know someone out there is going to insist that this sort of
thing can't possibly work. The standard argument I've heard from
Flash users who haven't tried this method is that Flash's capture
buffer has a built-in word-wrap, and this word-wrap will somehow
mess up the binary file. They've suggested that it might work if
Flash's word-wrap is turned off.

But no matter what the setting of word-wrap, Flash does not try
to wrap (place carriage returns into) binary data that is loaded
into the buffer. This has nothing to do with binary data; it's
just that Flash does not wrap *any* data that is placed in the
buffer. Word-wrap has no effect until you either start typing or
press F10 (the reformat key). If you use the capture buffer
merely as a storage area, no characters or data in the original
file are altered in any way, and the saved version of the buffer
is exactly the same as the original file.

Here's an example of using Flash to copy the program ARC.TTP
from one folder to another:

>ca on|
>ca cl|
>lo ca c:\archive\arc.ttp|
>sa ca d:\temp\arc.ttp|
>ca cl|

Of course, you can also change the name of the file when you copy
it. And that means that you can use Flash to rename files of any
kind merely by loading a file into the capture buffer, saving it
with a new filename, and then killing the original file. Here is
an example:

>ca on|
>ca cl|
>lo ca c:\flash\funckey.def|
>sa ca c:\flash\bbsfkey.def|
>ca cl|
>ki c:\flash\funckey.def|



Flash has "gosubs" just like BASIC and C
----------------------------------------


One of the biggest complaints about Flash from users who have
created their own Flash DO files is the apparent lack of a
"gosub" facility. A "gosub" is a variation on the familiar
"goto," which in Flash is called a "jmp." A "jmp" command forces
Flash to find its next instruction not at the following command
but at a label anywhere else in the DO script. It looks like
this:

>jmp SomeLabel|
...
>L: SomeLabel|

The problem with all "goto" commands, including Flash's "jmp," is
that the program does not automatically return to the point where
the "goto" instruction was issued. A "jmp" does not tell Flash to
go to another instruction and then return to the place it had
been; rather, it is a doorway, so to speak, that only opens in
one direction (unless, of course, you write the script with a
return "jmp" back to the original location -- something that can
be chancy if you're not really careful).

A "gosub" is a goto-and-return command, used to access such
things as subroutines that work with the main script. Here's a
simple one, an imaginary Flash "gosub" that calls up a help
screen any time a user presses <H>. You'd want a "gosub" used
here because the script should not have to proceed to any other
point except the "help" subroutine:

>L: top|
>al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0|
>ifi $X "Xmodem" jmp XmodemXfer|
>ifi $X "Quit" jmp Quit|
>ifi $X "Help" gosub HelpScreen|
>if ~X jmp top|

Another such subroutine might be a date-setting procedure. When
the main script is running, it can be programmed to check for a
current date; if it does not find one, the main script would then
use a "gosub" to branch to a date-setting subroutine, which would
return to the next command in the main script after it had run.

It would look something like this, if Flash had a "gosub"
(variable D would hold the date):

>mo ansi|
>ba 2400|
>if ~D gosub DateSet|
>di starbbs|

Here's another example, using an imaginary "gosub" to look for
caller passwords in a simple Flash-based BBS:

>L: top|
>hg|>** hang up|
ATS0=1|
>** send answer command to modem (on first ring)|
>wa "CONNECT"|
>send " Welcome to the Flashland BBS.|"|
>send "Please type your password: "|
>get $P|
>if ~P jmp top|>** reset modem if no response|
>gosub CheckPW|
>ifi $C "password OK" send "|You are now on line.|"|
>ifi $C "password OK" jmp mainmenu|
>send "|Password not found!|"|
>gosub GetNewPW|
>L: mainmenu|
...

In each case above, Flash actually *does* have a gosub that can
be used. In fact, there are two different ways of doing it. The
first involves spawning a new script that is executed from within
the current script. This uses the "do" command. Whenever another
DO file is executed from within a running DO file, the new script
is executed and then the command execution returns to the command
following the one that issued the "do" command -- a perfect
"gosub."

This method works very well, especially if the scripts are all
running from a fast hard drive. The primary drawback should be
obvious: Flash does not allow nested DO files past three levels,
so you should be careful to keep track of how many levels deep
you may be going when you nest any scripts.

There's another caution, too, which will be mentioned a little
later.

Here's another version of the first example given above, using a
nested DO file instead of the non-existent "gosub":

>L: top|
>al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0|
>ifi $X "Xmodem" jmp XmodemXfer|
>ifi $X "Quit" jmp Quit|
>ifi $X "Help" do help.do|
>if ~X jmp top|

And here is the second example above, using the "do" command as
a "gosub":

>mo ansi|
>ba 2400|
>if ~D do date.do|
>di starbbs|

Likewise, the third example would work fine if "do" commands were
used instead of "gosubs" where necessary.

The second way of getting "gosubs" in Flash is not used much,
judging from the scripts that I have seen. But it is quite
powerful, and does not have a nesting problem. It involves the
use of function-key strings -- commands that are inserted in
function keys 1 through 20 and called from a script using the
"go" command.

Whenever a "go" command is executed, the script continues at its
next command after the function-key string is passed to the
program. In actual execution, the "go" is a true "gosub."

What makes this even more useful is Flash's ability to program
function keys from within DO files themselves, using the "fk"
command. This means that the main script can set up a function
key in any way it wants, and then branch to it if needed.

To use this feature properly, you must understand how Flash
passes function-key strings to a function key. Because these
"fkey" commands are also script commands, you must be sure that
Flash does not execute them when it is merely loading them into
an fkey. The way to do it is to use single quote marks around the
entire fkey string; when Flash encounters a single quote mark, it
ignores all commands between that mark and the next one it comes
to. (Things can get complicated if you are also inserting quotes
into a function key, but Flash also has a way of getting around
that, as we'll see shortly.)

Let's change the first example above so that the "help"
subroutine is accessed through a function key. First, the fkey
must be set up; that's the second line in the example below.

>L: top|
>fk 1 '>$X|>vi help.txt|'|
>al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0|
>ifi $X "Xmodem" jmp XmodemXfer|
>ifi $X "Quit" jmp Quit|
>ifi $X "Help" go 1|
>if ~X jmp top|

A sharp-eyed Flash user may be able to notice that the same
effect might be achieved without using the equivalent of a
"gosub" in the example above, by changing one line and adding
another, while deleting the fkey loader, like this:

>L: top|
>al "[2][Xmodem transfer,|Quit or Help?][Xmodem|Quit|Help|" $X 0|
>ifi $X "Xmodem" jmp XmodemXfer|
>ifi $X "Quit" jmp Quit|
>ifi $X "Help" vi help.txt|
>ifi $X "Help" jmp top|
>if ~X jmp top|

But this method is not reliable once your commands become more
complicated. Using the "go" command is foolproof and should not
give you any trouble.

What about the problem of placing quote marks in commands when
you assign fkey strings from a DO file? Here's where this kind of
problem can arise: You may want your fkey to have quotes built
into the contents of the string, such as when you are assigning
an alert box to the function key. Alert box commands *must* have
quotes in them, as in the second line of the example above.

Here's how to do it. Use double quotes instead of single quotes
when you create the fkey string. In other words, place a double
quote in front of every double quote that you want to have Flash
pass through to the function key. Here's how it would look:

>ty |
>fk 1 '>al ""[2][Xmodem transfer?][Xmodem|Quit]"" $X 0|'|
>go 1|
>ifi $X "Xmodem" jmp XmodemXfer|
>ifi $X "Quit" jmp Quit|

By the way, the same method works in any situation in which you
want to pass a quote mark through Flash without having it changed
or acted on (when you are logging text to Flash's capture buffer,
for example).



Flash can be more than a program; it can be a shell
---------------------------------------------------


A shell is merely a program that runs other programs. The ST and
TT GEM desktops are shells, for example. But the most common
shells that advanced ST and TT users are likely to encounter are
command-line shells. An excellent shareware shell is
Tomshell.prg, which is distributed with STalker. Unix-like shells
are also common among some users.

Some shells let you set up function keys to run programs, and
others offer advanced batch-file capabilities.

Flash can do all that. All you need to do is try it.

To use Flash as a shell, run it from the GEM desktop and then set
up function keys that run your favorite programs. You'll probably
find that most of your programs run just fine -- except for other
telecommunications programs. Some of them will cause a conflict
with Flash over which one is controlling the modem port.

A function key that is set up to run a program should look like
this, if you set it up from a DO script:

>** setting up F4 to run STWriter...|
>fk 4 '>ex STWriter.prg|'|

Note that if the program you are running is not in the same
folder as Flash, you will have to do one of two things: Either
place the full pathname in the fkey command string, or change the
default directory to the program's directory before running it.
Some older GEM programs have resource files (files with a ".RSC"
extender) that won't be found unless you switch to the program's
folder first. Here are the two variations on the routine above,
with the second one needed to run some GEM programs:

>** setting up F4 to run STWriter...|
>fk 4 '>ex c:\stw\STWriter.prg|'|

>** setting up F4 to run STWriter...|
>fk 4 '>cd c:\stw\|>ex STWriter.prg|'|

After you run that command in a script, press F4 to run STWriter
within Flash. When you quit STWriter, Flash's familiar terminal
screen will reappear.

If you program and load function keys to run various programs,
you should be sure to save those function keys so that they are
available the next time you run Flash. You don't need to save
them as the default function keys; you can use another filename
and then load them by another function key. Here's an example on
how to do it from a DO file:

>** setting up fkeys and making an fkey loader.|
>sa fk funckey.def|>** saves current keys.|
>fk 1 '>fk|'|
>fk 2 '>cd c:\wp\|>ex wp.prg|'|
>fk 3 '>ex c:\icd\hdutils.prg|'|
...
>fk 19 '>ex c:\qf.prg|'|
>fk 20 '>lo shellkey.def|'|
>sa fk shellkey.def|

Function key 1, in this example, is the Help key. When you press
it, all it does is show you a list of function keys and their
assignments -- a handy way of seeing all 20 at once.

Fkey 20 is the loader. Flash always boots up with the function
keys that are in the file funckey.def, but you can switch easily
to a new set of fkeys by using the F20 method above.

(In my own setup, I've gone a step further. F20 loads a set of
function keys that are themselves separate fkey loaders. This way
I am able to have as many separate function keys as I want, since
F20 in the first loader file could also load *another* set of
fkey loaders, and so on for the second and third set.)

You may also want to note that function keys can also include
comments, like this (in a script routine that sets up an fkey):

>fk 5 '>** shows general help file|>vi genhelp.txt|'|

And you might find it handy to create function keys that do
nothing by themselves -- in other words, fkeys that do not
operate unless you press <return> after you press the fkey. The
one I've used the most is an fkey that clears Flash's capture
buffer if I press <return>. if I press <undo>, it cancels out. It
uses the comment command to show a comment in Flash's
command-line window (the one at the bottom of the terminal
screen).

Here is how to load it from a script:

>fk 10 '>ca cl **<return> clears buffer; <undo> cancels'|

You'll note that function key 10 is not written "properly" --
that is, it does not end the way fkeys are supposed to end, with a
"|" character. As a result, when you press F10, the commands in
the function key are not executed. But if you press <return>, the
missing "|" is supplied and the commands are executed. Pressing
<undo> clears the command line and cancels the fkey.



Flash can do Zmodem easily
--------------------------


The "fact" that Flash can't do Zmodem is one of the biggest
fictions among the Flash lore. Because Flash does not have a
"Zmodem" entry in the GEM Upload and Download menus, some users
assume that there is no way to do Zmodem transfers within Flash.
But all Flash needs is a Zmodem module. The best is Alan
Hamilton's shareware program XYZ, which comes in both GEM and
non-GEM versions (xyz.prg and xyz.ttp). Both are available from
GEnie and other telecomm sources.

When you are ready to do a Zmodem transfer, simply issue a "gem
xyz" or "ex xyz" command. (You must use the "gem" command if you
want to run a GEM program and be able to use your mouse.)

I've found xyz.ttp much easier to use, since you can pass
commands and filenames to the program from a function key. After
you press the fkey, type the rest of the information on the Flash
command line and press <return>. Here's a sample fkey as it would
be set up from a script:

>** fkey 11 to receive Zmodem, fkey 12 to send.|
>fk 11 '>ex xyz -r|'|
>fk 12 '>ex xyz -s '|

Note that the command in fkey 12 does not end. When fkey 12 runs,
it waits for your input, which in this case would be the filename
or wildcards for whatever you want to upload.



Flash is a graphics program
---------------------------


Can you see graphics without running another program within
Flash? You sure can. You can easily show a full-screen graphics
picture based on any Degas high-resolution or medium-resolution
picture. You do it by converting the Degas graphic to Vidtex, and
then using the "vi" (view) command in Flash. Flash's "vi" command
shows a text file on the screen, but if Flash is placed in its
Vidtex emulation mode (also "vi"), you'll see any Vidtex pictures
with the view command as well.

Included with this documentation is a copyrighted program,
VCONVERT.PRG, which converts pictures from Degas to Vidtex. The
program is freeware. Also with this documentation are a number of
Vidtex pictures that you can view with Flash/

To see Vidtex pictures, you should have the emulation mode set
to Vidtex. Here is a sample DO command line:

>mo vi|

To view them, use the other "vi" command. You can set up a
function key that needs your input to show the picture. Here's an
example:

>fk 7 '>vi |>** Type filename of Vidtex picture'|



Flash can automate your file backups
------------------------------------


Backup programs are great, and they're an absolute necessity if
you don't want to lose what's on your hard drive. But between
backups, you can use Flash to automatically save your files in
archives (compressed files that may contain many standard
files). The actual archiving, of course, is done by a program such
as LHARC or ARC; what Flash does is execute the archiver at
specified times and under specific conditions. Flash's DO language
and its variables make this quite easy.

Here's how it's done.

First, this method of archiving takes advantage of one of the
lesser known commands in both LHARC and ARC, the "update" command.
Normally, the main functions of LHARC or ARC are the creation and
extraction of archives. The commands to do this are "a" (archive)
and "e" (extract).

But if you use LHARC or ARC for backing up files, the command
that may be most useful is "u" (update). The update command
forces LHARC and ARC to look at the time-and-date stamp that is
always placed on a file. Each time the file is changed in any
way, the ST/TT operating system updates that time/date stamp. By
checking all the files in an archive for the time/date stamp,
the "update" command knows which files in the archive need to be
updated.

In a neat additional feature, "update" also *adds* any files to
the archive that are not there already.

This gives you a simple way of maintaining a separate,
continually updated copy of your essential files, without needing
to do anything more than running a DO script. If you are in the
habit of running a master script every day, as I do, you need do
no more than add a line to the master script to execute the
backup DO file.

I use just such a method to keep a backup archive of the auto
folder on my C: drive, and I also use it to keep a backup
archive of all my DO files. (Because I enjoy programming DO
scripts, I usually write new ones or change current ones every
few days.)

Using LHARC or ARC to update archives does place one extra
requirement on your computer: You should have a built-in clock,
or, if that is not feasible, you must make sure you enter the
current time and date each time you boot your ST. (All STe
models, Megas and TTs have clocks built in.) You can change your
computer's clock from the Atari CONTROL.ACC, from the company's
CPX-based XCONTROL.ACC, or from many other desk accessories and
programs.

Since you already have a modem, my advice for those who do not
have a built-in hardware clock -- and those who want to make
sure the clock that they do have in their computer is accurate --
is to use CALLTIME, a program written by Bob Areddy, and available
(at the time this is being written) as CALLTIM3. You may be able
to find it on a local BBS, and should be able to download it from
GEnie. (It may be called CALLTIM3.ARC or CALLTIM3.LZH.)

CALLTIME uses your modem to dial the U.S. Navy Observatory near
Washington, D.C. and pick up the precise time from the
observatory's atomic clock. It automatically sets your computer's
internal clock and hangs up. A call should not cost more than 15
to 30 cents at night. (My calls average about 14 cents, at a
distance of about 400 miles from Washington.)

If your computer has a built-in hardware clock, CALLTIME will
reset it, and it will remain accurate even when you have rebooted
after the computer has been turned off. (Hardware clocks are
always running, even if the computer is off.) If you do not have
a hardware clock, your ST still has a software clock, and it will
be set accurately and should remain accurate to within a few
seconds a month as long as your ST remains on.

Here are the essential parts of two scripts for automatic file
backup. The first backs up all new and altered files in the
C:\auto\ folder, and the second backs up DO files.


>** This script must have a folder in the C: root|
>** named AUTOFBAK. It creates and maintains an archive|
>** called AUTOFLDR.LZH in that folder.|
>cd c:\auto\|
>$X d:\arc\|>** path of the archive program; use yours.|
>ex $Xlharc u c:\autofbak\autofldr *.*|
>pa 1|
>ty |
>ty Auto folder backed up successfully!|
>ty|>ty|


>** This script must have a folder in the Flash directory|
>** named DO, and a folder inside that folder|
>** named BACKUPDO. Change the "cd c:\flash" command to|
>** your drive and folder path for Flash.|
>cd c:\flash\|
>$X D:\arc\|>** see comment above.|
>$Y "do\backupdo\"|
>ex $Xlharc u $Xdofiles.lzh do\*.DO|
>ty |
>ty Do scripts backed up successfully!|
>ty|>ty|


** A note about incompatible LHARC versions **


In the two examples above, the version of LHARC that is used is
the latest version of the so-called "Quester" LHARC, named for
Thomas Quester of Germany. Quester has done a lot to improve
LHARC, which was written by a Japanese programmer for IBM
compatible PCs. Quester's LHARC is almost fully compatible with
its current PC counterpart, now called LHA, but it is *not* fully
compatible with earlier versions of LHARC for the ST and TT. If,
as I do, you use the excellent desk accessory UNLZH to extract,
test or read the contents of LZH files, you should consider
using an additional command when you run LHARC from a DO file.

That command is actually a "switch" (an added instruction that
modifies a command), given as "-o" after the main command. The
"-o" switch forces LHARC to revert to an older compression
method that UNLZH accepts.

Here is how the command looks in a DO file line:

>ex $Xlharc u -o $Xdofiles.lzh do\*.DO|



Flash can maintain files by day and date
----------------------------------------


If your computer has a built-in hardware clock, or if you make
sure you set your ST's time and date each time you boot up (see
the note about CALLTIME above if you want it done by modem), you
can use the script DATE.DO to set some of Flash's variables to
the current day and date. DATE.DO, which is distributed in the
archive with this documentation, gets its information about the
day and date from a freeware program named TIMEDATE (or TD in
some versions), also distributed in the archive. TIMEDATE creates
a data file, stored on disk, that DATE.DO reads to interpret the
data needed for Flash's variables.

In DATE.DO, variable A is the full date in the U.S. format
(August 3, 1993). Variable B is the full date in Canadian format
(3 August, 1993). Variable D is the day in one or two digits (3
or 22); variable M is the month, spelled out (August); variable
O is the month in two digits (08); variable W is the year in two
digits; variable X is the year in four digits (1992), and
variable Y is the time that DATE.DO was run, using a European
version of the standard 24-hour format (14:42.15).



Flash can find its DO scripts and run them
------------------------------------------


Some of you may be familiar with Procomm Plus, the most popular
telecommunications program for IBM-compatible PCs. One nicety
about PC Plus is the way it automatically executes its scripts
even if you don't type the filename extender. In other words, even
though PC Plus ASPECT scripts, the equivalent of Flash's DO files,
are supposed to named FILENAME.ASP, you can run them by giving
the FILENAME part of the name without the .ASP at the end.

Too bad Flash can't do that -- or can it? Yes, it can, with a
little help from you.

First, we are assuming that you will, in fact, want to give all
your scripts the .DO extender. This makes them easy to find and
easy to sort, and it also makes sure there is no doubt about
what they, um, "do" ... if you'll pardon the pun.

So the next step is to write a short script called "DO" -- yes,
that's the entire name, with no extender. It will be the *only*
script without an extender. We can get away with this, for one
DO file only, because this one will be the script that lets you
run the others without bothering with typing the ".DO" extender.

Here's the essential part of the script:


>** filename: DO

Tip: run this from a function key.

This script assumes that the DO files are located in the current
directory or in a folder named DO one level down in the current
directory.

|

>L: top|
>$Z .|
>op *.do|
>if op jmp getdoname|
>op do\*.do|
>if op jmp setc.d|
>** Do NOT take out the double quotes in the next line!|
>qu "Folder for DO files|(don''t type ""\""):" $Z|
>op $Z\*.do|
>if op jmp getdoname|
>if ~op al "[3][Folder not found!][Rats!|Quit]" $X 2|
>end|
>L: getdoname|
>cd $Z|
>qu "Execute which DO script?|(Type ""?"" for a list.)" $X|
>ifi $X "?" jmp listdo|
>op $X|
>if ~op jmp adddo|
>if op jmp doit|
>L: nofile|
>al "[3][File not found!|Try again?][Yes|No]" $X 1|
>ifi $X "Yes" jmp getdoname|
>end|
>L: adddo|
>$Y $X.do|
>$X $Y|
>op $X|
>if ~op jmp nofile|
>L: doit|
>do $X|
>end|
>L: listdo|
>dd *.do filelist.txt|
>vi filelist.txt|
>jmp getdoname|
>L: setc.d|
>$Z do\|
>jmp getdoname|
>** end|



<--== E N D ==-->